Python Argparse למתקדמים: שליטה בפקודות משנה ומחלקות פעולה מותאמות אישית

מודול argparse של פייתון הוא כלי רב עוצמה ליצירת ממשקי שורת פקודה (CLIs). בעוד שהשימוש הבסיסי בו פשוט יחסית, argparse מציע תכונות מתקדמות המאפשרות יצירת ממשקי CLI מתוחכמים וידידותיים למשתמש. פוסט זה צולל לשתי תכונות מתקדמות כאלה: פקודות משנה (subcommands) ומחלקות פעולה מותאמות אישית (custom action classes).

מדוע להשתמש ב-Argparse למתקדמים?

עבור סקריפטים פשוטים עם אפשרויות מעטות בלבד, הפונקציונליות הבסיסית של argparse עשויה להספיק. עם זאת, ככל שהסקריפטים שלכם גדלים במורכבותם ובתפקודיהם, ממשק CLI מובנה ומאורגן יותר הופך לחיוני. תכונות מתקדמות של argparse מסייעות ל:

• שיפור חוויית המשתמש: לספק ממשק ברור ואינטואיטיבי למשתמשים.
• שיפור תחזוקתיות הקוד: לארגן את הקוד במודולים לוגיים, מה שמקל על הבנתו ותחזוקתו.
• הגברת הפונקציונליות: לתמוך בתהליכי עבודה מורכבים ובפעולות מרובות בתוך סקריפט יחיד.
• קידום שימוש חוזר: ליצור רכיבים רב-פעמיים שניתן ליישם בחלקים שונים של היישום שלכם.

פקודות משנה: ארגון ממשקי CLI מורכבים

פקודות משנה הן דרך לקבץ פקודות קשורות תחת פקודה ראשית אחת. זה שימושי במיוחד עבור יישומים המבצעים מגוון משימות נפרדות. חשבו על Git, לדוגמה. הוא משתמש בפקודות משנה באופן נרחב: git commit, git push, git pull, וכן הלאה. לכל פקודת משנה יש קבוצת ארגומנטים ואפשרויות משלה.

מימוש פקודות משנה עם argparse

כדי לממש פקודות משנה עם argparse, משתמשים במתודה add_subparsers(). הנה דוגמה בסיסית:

            
import argparse

# Create the main parser
parser = argparse.ArgumentParser(description='A simple example with subcommands')

# Create the subparser
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# Create the 'add' subcommand
add_parser = subparsers.add_parser('add', help='Add two numbers')
add_parser.add_argument('x', type=int, help='First number')
add_parser.add_argument('y', type=int, help='Second number')

# Create the 'subtract' subcommand
subtract_parser = subparsers.add_parser('subtract', help='Subtract two numbers')
subtract_parser.add_argument('x', type=int, help='First number')
subtract_parser.add_argument('y', type=int, help='Second number')

# Parse the arguments
args = parser.parse_args()

# Perform the action based on the subcommand
if args.command == 'add':
    result = args.x + args.y
    print(f'The sum is: {result}')
elif args.command == 'subtract':
    result = args.x - args.y
    print(f'The difference is: {result}')
else:
    parser.print_help()

            

              
                Copy
              
            
          

בדוגמה זו:

• אנו יוצרים מנתח ראשי (parser) באמצעות argparse.ArgumentParser().
• אנו מוסיפים מנתח-משנה באמצעות parser.add_subparsers(dest='command', help='Available commands'). הארגומנט dest מציין את התכונה שתאחסן את שם פקודת המשנה שנבחרה.
• אנו יוצרים שתי פקודות משנה, 'add' ו-'subtract', באמצעות subparsers.add_parser().
• לכל פקודת משנה יש סט ארגומנטים משלה (x ו-y).
• אנו מנתחים את הארגומנטים באמצעות parser.parse_args().
• אנו בודקים את הערך של args.command כדי לקבוע איזו פקודת משנה נבחרה ולאחר מכן מבצעים את הפעולה המתאימה.

כדי להריץ את הסקריפט הזה, תשתמשו בפקודות כמו:

python your_script.py add 5 3
python your_script.py subtract 10 2

טכניקות מתקדמות לפקודות משנה

1. שימוש בפונקציות לטיפול בפקודות משנה

גישה מאורגנת יותר היא להגדיר פונקציות נפרדות שיטפלו בכל פקודת משנה. זה משפר את קריאות הקוד ואת התחזוקתיות שלו.

            
import argparse

def add(args):
    result = args.x + args.y
    print(f'The sum is: {result}')

def subtract(args):
    result = args.x - args.y
    print(f'The difference is: {result}')

# Create the main parser
parser = argparse.ArgumentParser(description='A simple example with subcommands')

# Create the subparser
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# Create the 'add' subcommand
add_parser = subparsers.add_parser('add', help='Add two numbers')
add_parser.add_argument('x', type=int, help='First number')
add_parser.add_argument('y', type=int, help='Second number')
add_parser.set_defaults(func=add)

# Create the 'subtract' subcommand
subtract_parser = subparsers.add_parser('subtract', help='Subtract two numbers')
subtract_parser.add_argument('x', type=int, help='First number')
subtract_parser.add_argument('y', type=int, help='Second number')
subtract_parser.set_defaults(func=subtract)

# Parse the arguments
args = parser.parse_args()

# Call the function associated with the subcommand
if hasattr(args, 'func'):
    args.func(args)
else:
    parser.print_help()

            

              
                Copy
              
            
          

כאן, אנו משתמשים ב-set_defaults(func=...) כדי לשייך פונקציה לכל פקודת משנה. לאחר מכן, אחרי הניתוח, אנו קוראים לפונקציה המתאימה אם היא קיימת.

2. קינון פקודות משנה

ניתן לקנן פקודות משנה כדי ליצור ממשקי CLI מורכבים והיררכיים עוד יותר. לדוגמה, שקלו CLI לניהול משאבי ענן:

cloud compute instance create --name my-instance --region us-east-1
cloud storage bucket list --project my-project

בדוגמה זו, cloud היא הפקודה הראשית, compute ו-storage הן פקודות משנה, ו-instance ו-bucket הן פקודות משנה-משנה.

3. דוגמה מהעולם האמיתי: כלי בינאום (Internationalization)

דמיינו כלי לניהול תרגומים ביישום רב-לשוני. תוכלו להשתמש בפקודות משנה כדי לארגן את הפעולות השונות:

translation tool add-language --code fr_FR --name "French (France)"
translation tool extract-strings --source-dir src
translation tool translate --target-language es_ES --source-file strings.pot

גישה זו מאפשרת הפרדה ברורה של תחומי אחריות והופכת את הכלי לקל יותר לשימוש ולתחזוקה, במיוחד כאשר מתמודדים עם שפות רבות ותהליכי תרגום החלים במדינות שונות.

מחלקות פעולה מותאמות אישית: התאמת ניתוח הארגומנטים

argparse מאפשר להגדיר מחלקות פעולה מותאמות אישית כדי להתאים את אופן עיבוד הארגומנטים. זה שימושי לתרחישים שבהם התנהגות ברירת המחדל של עיבוד הארגומנטים אינה מספקת. מחלקת פעולה היא מחלקה שיורשת מ-argparse.Action ודורסת את המתודה __call__.

יצירת מחלקת פעולה מותאמת אישית

הנה דוגמה למחלקת פעולה מותאמת אישית הממירה ארגומנט לאותיות גדולות (uppercase):

            
import argparse

class ToUpper(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if isinstance(values, list):
            setattr(namespace, self.dest, [v.upper() for v in values])
        else:
            setattr(namespace, self.dest, values.upper())

# Create the parser
parser = argparse.ArgumentParser(description='Example with custom action')

# Add an argument with the custom action
parser.add_argument('--name', action=ToUpper, help='Name to convert to uppercase')
parser.add_argument('--cities', action=ToUpper, nargs='+', help='List of cities to convert to uppercase')

# Parse the arguments
args = parser.parse_args()

# Print the result
if args.name:
    print(f'Name: {args.name}')
if args.cities:
    print(f'Cities: {args.cities}')

            

              
                Copy
              
            
          

בדוגמה זו:

• אנו מגדירים מחלקה ToUpper שיורשת מ-argparse.Action.
• המתודה __call__ נקראת כאשר נתקלים בארגומנט. היא מקבלת את הארגומנטים הבאים:
  • parser: אובייקט ה-ArgumentParser.
  • namespace: אובייקט ה-namespace שבו מאוחסנים הארגומנטים המנותחים.
  • values: הערך/ערכים של הארגומנט.
  • option_string: מחרוזת האפשרות ששימשה להפעלת פעולה זו (למשל, --name).
• בתוך המתודה __call__, אנו ממירים את הערך לאותיות גדולות באמצעות values.upper() ומאחסנים אותו ב-namespace באמצעות setattr(namespace, self.dest, values.upper()).
• אנו מוסיפים ארגומנט למנתח באמצעות parser.add_argument('--name', action=ToUpper, help='Name to convert to uppercase'). אנו מציינים את הארגומנט action כמחלקת הפעולה המותאמת אישית שלנו.

כדי להריץ את הסקריפט הזה, תשתמשו בפקודות כמו:

python your_script.py --name john
python your_script.py --cities london paris tokyo

מקרי שימוש למחלקות פעולה מותאמות אישית

1. אימות קלט

ניתן להשתמש במחלקות פעולה מותאמות אישית כדי לאמת קלט ולהעלות שגיאה אם הקלט אינו תקין. לדוגמה, ניתן ליצור מחלקת פעולה שבודקת אם קובץ קיים או אם מספר נמצא בטווח מסוים.

            
import argparse
import os

class FileMustExist(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if not os.path.exists(values):
            raise argparse.ArgumentTypeError(f'File not found: {values}')
        setattr(namespace, self.dest, values)

parser = argparse.ArgumentParser(description='Example validating file existence.')
parser.add_argument('--input-file', action=FileMustExist, help='Path to input file.')

args = parser.parse_args()

print(f'Input file: {args.input_file}')

            

              
                Copy
              
            
          

2. המרת יחידות

ניתן להשתמש במחלקות פעולה מותאמות אישית להמרת יחידות. לדוגמה, ניתן ליצור מחלקת פעולה הממירה טמפרטורות מצלזיוס לפרנהייט.

3. טיפול במבני נתונים מורכבים

אם אתם צריכים לנתח ארגומנטים למבני נתונים מורכבים (למשל, מילונים, רשימות של אובייקטים), תוכלו להשתמש במחלקות פעולה מותאמות אישית כדי לטפל בלוגיקת הניתוח.

4. דוגמה: טיפול באזורי זמן

שקלו יישום שצריך לטפל בתאריכים ובשעות באזורי זמן שונים. ניתן להשתמש במחלקת פעולה מותאמת אישית כדי לנתח מחרוזת תאריך ולהמיר אותה לאזור זמן ספציפי באמצעות ספריות כמו pytz.

            
import argparse
import datetime
import pytz

class TimeZoneConverter(argparse.Action):
    def __init__(self, option_strings, dest, timezone=None, **kwargs):
        super().__init__(option_strings, dest, **kwargs)
        self.timezone = timezone

    def __call__(self, parser, namespace, values, option_string=None):
        try:
            dt = datetime.datetime.fromisoformat(values)
            if self.timezone:
                tz = pytz.timezone(self.timezone)
                dt = tz.localize(dt)
            setattr(namespace, self.dest, dt)
        except ValueError:
            raise argparse.ArgumentTypeError(f"Invalid date/time format.  Use ISO format (YYYY-MM-DDTHH:MM:SS): {values}")
        except pytz.exceptions.UnknownTimeZoneError:
            raise argparse.ArgumentTypeError(f"Invalid Timezone: {self.timezone}")

parser = argparse.ArgumentParser(description='Example with timezone conversion.')
parser.add_argument('--event-time', action=TimeZoneConverter, timezone='America/Los_Angeles', help='Event time in ISO format (YYYY-MM-DDTHH:MM:SS). Converts to America/Los_Angeles timezone.')

args = parser.parse_args(['--event-time', '2024-10-27T10:00:00'])

print(f'Event Time (Los Angeles): {args.event_time}')

            

              
                Copy
              
            
          

דוגמה זו מציגה כיצד פעולות מותאמות אישית יכולות לטפל בהמרות של אזורי זמן באמצעות ספריית pytz, ומדגימה שימוש מתוחכם יותר שהוא רלוונטי גלובלית.

שיטות עבודה מומלצות לשימוש ב-Argparse מתקדם

• שמרו על פשטות: אל תסבכו יתר על המידה את ה-CLI שלכם. השתמשו בפקודות משנה ובפעולות מותאמות אישית רק בעת הצורך.
• ספקו הודעות עזרה ברורות: כתבו הודעות עזרה ברורות ותמציתיות לכל פקודה וארגומנט. השתמשו בארגומנט help ב-add_argument() באופן נרחב.
• אמתו קלט: תמיד אמתו קלט משתמש כדי למנוע שגיאות ופגיעויות אבטחה.
• השתמשו במוסכמות שיום עקביות: עקבו אחר מוסכמות שיום עקביות עבור פקודות, ארגומנטים ואפשרויות. שקלו להשתמש ב-kebab-case (--my-option) עבור שמות אפשרויות ארוכים.
• בדקו ביסודיות: בדקו את ה-CLI שלכם ביסודיות עם קלטים ותרחישים שונים.
• תעדו את ה-CLI שלכם: ספקו תיעוד מקיף עבור ה-CLI שלכם, כולל דוגמאות כיצד להשתמש בכל פקודה וארגומנט. כלים כמו Sphinx יכולים ליצור תיעוד מהקוד שלכם.
• שקלו לוקליזציה: אם ה-CLI שלכם מיועד לקהל גלובלי, שקלו לבצע לוקליזציה של הודעות העזרה וטקסטים אחרים הפונים למשתמש.

סיכום

פקודות משנה ומחלקות פעולה מותאמות אישית הם כלים רבי עוצמה ליצירת ממשקי CLI מתוחכמים וידידותיים למשתמש עם argparse. על ידי שליטה בתכונות מתקדמות אלו, תוכלו לבנות יישומי שורת פקודה חזקים, ניתנים לתחזוקה ומדרגיים העונים על הצרכים של בסיס משתמשים מגוון. מניהול יישומים רב-לשוניים ועד לטיפול באזורי זמן ברחבי העולם, האפשרויות הן עצומות. אמצו טכניקות אלו כדי להעלות את פיתוח הסקריפטים וכלי שורת הפקודה שלכם בפייתון לשלב הבא.